Add Microsoft Foundry (azure-ai-projects v2) Python instructions 🤖🤖🤖 - #2539
Add Microsoft Foundry (azure-ai-projects v2) Python instructions 🤖🤖🤖#2539passadis wants to merge 3 commits into
Conversation
github-actions
Bot
added
instructions
🔒 PR Risk Scan ResultsScanned 1 changed file(s).
|
There was a problem hiding this comment.
Pull request overview
Adds Python instructions for Microsoft Foundry’s azure-ai-projects v2 SDK and publishes them in the instruction catalog.
Changes:
- Documents versioned agents, conversations, tools, and lifecycle guidance.
- Adds the instruction to the generated documentation index.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
instructions/microsoft-foundry.instructions.md |
Adds Microsoft Foundry Python SDK guidance and examples. |
docs/README.instructions.md |
Registers the new instruction. |
Suppressed comments (4)
instructions/microsoft-foundry.instructions.md:55
create_versiondoes not point the agent endpoint at the new version. The official basic sample callsagents.update_detailswith anAgentEndpointConfigselecting the created version before opening the agent-scoped OpenAI client; without that, a new agent lacks usable routing and an existing agent can keep routing to older versions. Configure the endpoint first, and preserve/restore its prior configuration for a temporary sample.
with project_client.get_openai_client(agent_name=agent_name) as openai_client:
instructions/microsoft-foundry.instructions.md:15
az loginis only needed whenDefaultAzureCredentialuses the Azure CLI credential during local development; it is neither required nor appropriate for managed/workload identity deployments. Qualify this instruction so generated production guidance does not depend on an interactive CLI login.
- Entra ID is the **only** supported auth. Use `azure.identity.DefaultAzureCredential`; run `az login` first. There is **no** API-key auth and **no** `from_connection_string()` on the client.
instructions/microsoft-foundry.instructions.md:91
previous_response_idis not cheaper than a Conversation: prior input tokens are still processed and billed on subsequent Responses calls. It changes how state is managed, not token cost, so the cost claim is misleading.
For simple stateless follow-ups you can instead chain with `previous_response_id=response.id` on `responses.create` — cheaper than a full conversation when you only need to reference the prior turn.
instructions/microsoft-foundry.instructions.md:172
logging_enable=Trueenables full transport traffic logging, including request/response bodies, and header sanitization is skipped in that mode unless a filtered handler is installed. Describing this only as a DEBUG-level switch can cause generated diagnostics to expose bearer tokens and prompt/user data. Prefer the SDK's filtered console-logging path and explicitly warn that payloads may still be sensitive.
- Enable request/response logging with `logging_enable=True` **and** logger level `DEBUG` (redacted unless level is DEBUG); or set `AZURE_AI_PROJECTS_CONSOLE_LOGGING=true`.
|
|
||
| ## Package and versions | ||
|
|
||
| - Install: `pip install "azure-ai-projects>=2.0.0"` (async also needs `pip install aiohttp`). |
There was a problem hiding this comment.
All five points were valid and are addressed in 6b97243:
| Point | Fix |
|---|---|
| Version floor too low (L14) | Raised to >=2.3.0; noted which APIs need 2.1/2.2 |
| Missing endpoint routing (L55) | Added explicit update_details + AgentEndpointConfig version-selection step to the basic example |
az login vs. prod auth (L15) |
Qualified — local dev uses CLI credential; Azure uses managed/workload identity |
previous_response_id cost claim (L91) |
Reworded as a state-management choice, not a token-cost saving |
| Logging security (L172) | Expanded to warn that body logging can leak tokens/prompts; prefer the filtered console path |
Also verified via an A/B test in VS Code: with the file off, Copilot emits the deprecated create_agent/threads/runs API; with it on, it emits the correct v2 create_version + PromptAgentDefinition + Responses flow.
Verification: A/B tested in VS Code (instructions on vs. off)I verified the uplift with an A/B test in VS Code using an identical prompt — "Create an Azure AI Foundry agent that answers general questions using the ❌ Instructions OFF — Copilot generates the deprecated pre-v2 agent = agents_client.create_agent(model=..., name=..., instructions=...)
thread = agents_client.threads.create()
agents_client.messages.create(thread_id=thread.id, role="user", content="...")
run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
messages = agents_client.messages.list(thread_id=thread.id, order="asc") # reply via message.text_messages[-1].text.value✅ Instructions ON — Copilot generates the correct v2 pattern: versioned agents via version = project_client.agents.create_version(
agent_name=agent_name,
definition=PromptAgentDefinition(model=model, instructions="..."),
)
with project_client.get_openai_client(agent_name=agent_name) as openai_client:
response = openai_client.responses.create(input="...")
print(response.output_text)The updated instructions don’t just rename methods — they force Copilot to abandon the old threads/runs mental model and operate fully in the Responses API paradigm. That’s exactly why the file’s field notes describe the “fail on first attempts → re‑ground → re‑code” cycle: the model was still reasoning in v1 patterns. By front‑loading the correct framing, you get v2‑style output immediately, without the usual correction loop. Happy to attach full files-outputs ! |
…x auth/cost/logging notes
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (1)
instructions/microsoft-foundry.instructions.md:204
- Remove this unmatched closing fence. All preceding Python blocks are already closed, so this creates a stray empty code block at the end of the rendered instruction.
</details>
Pull Request Checklist
npm startand verified thatREADME.mdis up to date.mainbranch for this pull request.Description
Adds
instructions/microsoft-foundry.instructions.md— guidance for building agents with the Microsoft Foundry SDK (azure-ai-projectsv2) in Python.Why it adds uplift beyond default model behavior:
azure-ai-projectswas substantially reshaped in v2. Default Copilot output (trained on 1.x / the oldazure-ai-agentsthread-run-message API) generates code that no longer works — e.g.create_agent/threads.create/runs.create_and_process_run/messages.list. This file encodes the current, correct pattern: versioned agents viaagents.create_version(... PromptAgentDefinition ...), interaction through the OpenAI-compatible client (get_openai_client→ Responses + Conversations), tool attachment in the definition, the client-sideFunctionToolloop,allow_previewsemantics, and version-based canary rollout. Every snippet is derived from the official v2 SDK samples.Type of Contribution
Additional Notes
This file is grounded in a repeatedly observed real-world failure mode: in Copilot-assisted Foundry projects, Copilot defaults to the deprecated thread/run/message API, fails the first attempts, and only recovers after re-checking Microsoft Learn / the Microsoft Docs MCP server and re-coding against v2. These instructions front-load that correction so working v2 code is produced on the first pass. Verified against the official
azure-ai-projects>=2.0.0samples; rannpm startand confirmed the README tables are up to date.🤖 This PR was prepared with AI-agent assistance (disclosed per repo convention via the title marker).
By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.